The following sections describe changes in the way ColorSync 2.5 stores and manages profile information.
ColorSync 2.5 creates a cache file (containing private data) in the Preferences folder to keep track of all currently-installed profiles. The cache stores key information about each profile, using a smart algorithm that avoids rebuilding the cache unless the profile folder has changed.
ColorSync takes advantage of the profile cache to speed up profile searching. This optimized searching can help your application speed up some operations, such as displaying a pop-up menu of available profiles.
ColorSync's intelligent cache scheme provides the following advantages in profile management:
Note, however, that calls to the standard ColorSync search routines cannot take full advantage of the profile cache. For example, with the CMNewProfileSearch
routine, the caller passes in a search criteria and gets back a list of profiles that match that criteria. Before version 2.5, ColorSync had to open each profile to build the list, and the caller was likely to open each profile again after getting the list back. With version 2.5, ColorSync can at least use the profile cache to narrow down the list (unless the search criteria asks for all profiles!), but it cannot fully optimize the search process.
The next section describes a new routine added to the ColorSync API to take full advantage of the profile cache.
A flexible new routine, CMIterateColorSyncFolder
, takes advantage of the profile cache to provide truly optimized searching and quick access to profile information.
The CMIterateColorSyncFolder
routine iterates over the available profiles. It is defined as follows:
pascal CMError CMIterateColorSyncFolder ( CMProfileIterateUPP proc, unsigned long * seed, unsigned long * count, void * refCon);
proc
|
A universal procedure pointer of type CMProfileIterateUPP, which is described in CMProfileIterateProcPtr
. If you do not wish to receive callbacks, pass nil
for this parameter. Otherwise, pass a pointer to your callback routine.
|
seed
|
A pointer to a value of type long. The first time you call CMIterateColorSyncFolder, you typically set the value to 0. In subsequent calls, you set the value to the seed value obtained from the previous call. ColorSync uses the value in determining whether to call your callback routine, as described in the discussion for this function.On return, the value is the current seed for the profile cache (unless you pass nil, as described in the discussion).
|
count
|
A pointer to a value of type long. On return, the value is the number of available profiles. CMIterateColorSyncFolder provides the number of profiles even when no iteration occurs (unless you pass nil, as described in the discussion below). To determine the count alone, without iteration, call CMIterateColorSyncFolder and pass a value of nil for all parameters except count.
|
refCon
|
A pointer to arbitrary data, supplied by you, that ColorSync passes to your callback routine. If you pass nil for this parameter, ColorSync passes nil to your callback routine.
|
| function result |
A result code of type CMError. If your callback function returns an error, CMIterateColorSyncFolder stops iterating and returns the error value to its caller (presumably your code). See Advanced Color Imaging on the Mac OS for a list of ColorSync-specific result code values.
|
When your application needs information about the currently available profiles, it calls the CMIterateColorSyncFolder
routine, which in turn calls your callback routine once for each profile. Even though there may be many profiles available, ColorSync can use its profile cache to return profile information quickly, and (if the cache is valid) without having to open any profiles. For each profile, ColorSync returns the profile header, script code, name, and location. As a result, your routine may be able to perform its function, such as building a list of profiles to display in a pop-up menu, without further effort (such as opening a file-based profile).
Before calling CMIterateColorSyncFolder
for the first time, you typically set seed
to 0. ColorSync compares 0 to its current seed for the profile cache. It isn't likely they will match--the odds are roughly one in two billion against it. Therefore, the routine iterates through all the profiles in the cache, calling your callback routine once for each profile. CMIterateColorSyncFolder
then returns the actual seed value in seed
(unless you passed nil
for that parameter).
If you pass the returned seed value in a subsequent call, and if there has been no change in the available profiles, the passed seed will match the stored cache seed and no iteration will take place.
Note that you can pass a nil
pointer for the seed
parameter without harm. The result is the same as if you passed a pointer to 0, in that the function iterates through the available profiles, calling your callback routine once for each profile. However, the function doesn't return a seed value, since you haven't passed a valid pointer.
You can force ColorSync to call your callback routine (if any profiles are available) by passing a nil
pointer or by passing 0 for the seed value. But suppose you have an operation, such as building a pop-up menu, that you only want to perform if the available profiles have changed. In that case, you pass the seed value from a previous call to CMIterateColorSyncFolder
. If the profile folder has not changed, ColorSync will not call your callback routine.
Note that if there are no profiles available, ColorSync does not call your callback routine.
nil
for any or all of the parameters to the CMIterateColorSyncFolder
function. If you pass nil
for all of the parameters, calling the function merely forces rebuilding of the profile cache, if necessary.
The universal procedure pointer callback routine passed as a parameter to CMIterateColorSyncFolder
is defined as follows:
pascal OSErr (*CMProfileIterateProcPtr ) (CMProfileIterateData *iterateData, void *refCon);
iterateData
|
A pointer to a structure of type CMProfileIterateData (defined in the next section). On return, the structure contains profile information for the current profile (as the CMIterateColorSyncFolder routine iterates over all available profiles).
|
refCon
|
A pointer to arbitrary data you pass to theCMIterateColorSyncFolder routine and it, in turn, passes to your callback routine.
|
| callback return value |
A result code of type CMError. If your callback function returns an error, CMIterateColorSyncFolder stops iterating and returns the error value to its caller (presumably your code). See Advanced Color Imaging on the Mac OS for a list of ColorSync-specific result codes. |
When you call CMIterateColorSyncFolder, you pass a universal procedure pointer of type CMProfileIterateProcPtr that points to a function you provide. Your function definition is based on this definition of CMProfileIterateProcPtr.
The ColorSync Manager defines the CMProfileIterateData structure to provide your CMProfileIterateProcPtr callback routine with a description of a profile during an iteration through the available (or specified) profiles. The structure is defined as follows:
struct CMProfileIterateData {
unsigned long dataVersion; /* cmProfileIterateDataVersion1 */
CM2Header header;
ScriptCode code;
Str255 name;
CMProfileLocation location;
};
typedef struct CMProfileIterateData CMProfileIterateData;dataVersion
| A value identifying the version of the structure. Currently set to
cmProfileIterateDataVersion1.
|
header
| A ColorSync version 2.x profile header structure, containing information such as the profile size, type, version, and so on. |
code
| A script code identifying the script system used for the profile description. |
name
| The profile name. |
location
| A structure specifying the profile location. With ColorSync 2.5, the location is always file-based, but that may not be true for future versions. Your code should always verify that the location structure contains a file specification before attempting to use it. |